home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 February: Tool Chest / Apple Developer CD Series Tool Chest February 1996 (Apple Computer)(1996).iso / Tool Chest / Testing & Debugging / Virtual User tools / VU Assist Modules for MacApp / Assist Module MA 2.0.1 / READ ME FIRST!
Encoding:
Text File  |  1993-09-17  |  9.2 KB  |  223 lines  |  [TEXT/MPS ]
  1. **************************************************************************
  2. VUAssist, The V.U. Assistance Module for MacApp Applications
  3. **************************************************************************
  4.  
  5. In order to find the location of items in windows for V.U., Agent VU peruses 
  6. the content list of windows and the item list of dialogs.  For applications 
  7. which are not built with MacApp, these data structures can be accessed via 
  8. global variables by Agent VU.  For MacApp applications, however, items in 
  9. windows are subclasses of the class TView, which are not available to the 
  10. Agent via global data structures.   As a result, Agent VU can’t provide any 
  11. information about these items to V.U. in the normal way.
  12.  
  13. To work around this problem, Agent VU provides a hook which allows an 
  14. application to assist Agent VU by providing information about itself.  
  15. In this folder, we’ve provided VUAssist, an assistance module for MacApp 
  16. applications which can be hooked onto Agent VU to provide information about 
  17. a MacApp application. A user can build a MacApp application with VUAssist 
  18. and then test the application with V.U..  V.U. will "recognize" many of the
  19. application's views which translate into standard user interface items: buttons,
  20. scroll bars, checkboxes, static text, editable text fields, popup menus, etc.
  21.  
  22. The module exists as a unit called UVUAssist.  The unit consists of four files:   
  23. VUAssist.p, VUAssist.inc1.p, VUAssist.inc2.p, and VUAssist.a.
  24.  
  25.  
  26. -----------------------------------------------------------------------------
  27. What's New in this Version - 1.0d10
  28. -----------------------------------------------------------------------------
  29.  
  30. 1) VUAssist has now been defined as a descendant of TEvtHandler.  This allows 
  31. VUAssist to be installed as a cohandler.  The frequency with which VUAssist's 
  32. DoIdle routine is called can now be controlled. This gives the user of VUAssist 
  33. a convenient way to control the responsiveness of the application to Virtual User.
  34.  
  35. 2) VUAssist's handling of TGridView objects has changed somewhat.  The cells of 
  36. TGridView objects now appear as "contentItems" to V.U. as opposed to "userItems".  
  37. This is more consistent with V.U.'s interface item hierarchy.  Useritems are 
  38. really intended to describe Dialog Manager userItems while contentItems are 
  39. effectively the "base class" of all interface items in V.U..  Since there is no 
  40. class of interface items in V.U. which is intended to describe the cells of 
  41. gridviews, they should be considered to belong to the "base class", contentItem.
  42.  
  43. 3) The feature of VUAssist which maps the cells of gridviews to "contentitems" 
  44. can be disabled through the boolean gridItemSupport argument to the IVUAssist 
  45. method.
  46.  
  47. 4) The implementation of some of the methods of VUAssist have been modified to 
  48. improve performance.
  49.  
  50. 5) Applications built with VUAssist would sometimes crash if running on a Mac 
  51. Plus when V.U. tried to manipulate a "Save As…" dialog.  This problem has been 
  52. fixed in this version of VUAssist.
  53.  
  54. !!!!! NOTICE !!!!!
  55. 6) The instructions for building VUAssist into your application have changed 
  56. slightly since the 1.0d7 version, which was shipped with V.U. 1.0 final.  
  57. Therefore the instructions given in the Virtual User General Reference are not 
  58. valid for this version. The new instructions are given below.
  59.  
  60.  
  61. -----------------------------------------------------------------------------
  62. How to Use VUAssist
  63. -----------------------------------------------------------------------------
  64.  
  65. To build VUAssist into your MacApp application, follow the instructions
  66. below.  
  67.  
  68. For applications written in Object Pascal:
  69.  
  70. 1)  Modify your MAMake file to include the following:
  71.  
  72.     •    add the following to the list of OtherInterfaces
  73.         
  74.         "{SrcApp}UVUAssist.a" ∂
  75.         "{SrcApp}UVUAssist.p" ∂
  76.         
  77.     •    add the following to the list of OtherLinkFiles
  78.         
  79.         "{ObjApp}UVUAssist.a.o" ∂
  80.         "{ObjApp}UVUAssist.p.o" 
  81.     
  82.     •    add the additional dependency:
  83.  
  84.         "{ObjApp}UVUAssist.p.o"    ƒ ∂
  85.                     "{SrcApp}UVUAssist.p" ∂
  86.                     "{SrcApp}UVUAssist.inc1.p" ∂
  87.                     "{SrcApp}UVUAssist.inc2.p" ∂
  88.                     {MacAppIntf} ∂
  89.                     {BuildingBlocksIntf}
  90.                             
  91. 2)     Modify or subclass your descendant of TApplication to do the following:
  92.                             
  93.     •    In MyApplication.IApplication, you must execute this:
  94.             NEW(gVUAssist);
  95.             FailNil(gVUAssist);
  96.             gVUAssist.IVUAssist(gridItemSupport); { gridItemSupport must be a boolean 
  97.                                                     expression.  See "Altering the 
  98.                                                     behavior of VUAssist for an 
  99.                                                     explanation of gridItemSupport }
  100.     •    In MyApplication.AboutToLoseControl you must execute this:
  101.             gVUAssist.SuspendMole;
  102.  
  103.     •    In MyApplication.RegainControl you must execute this:
  104.             gVUAssist.ResumeMole;
  105.  
  106.     •    In MyApplication.Close you must execute this BEFORE calling INHERITED Close:
  107.             SELF.InstallCohandler(gVUAssist,false);
  108.  
  109. 3)    Include the unit UVUAssist in your USES clause where appropriate.  Other units, 
  110.     such as UPrinting, UTEView, UDialog, and UGridView may need to be included along 
  111.     with UVUAssist if they are not already.
  112.  
  113.  
  114. For applications written in C++:
  115.  
  116. 1)  Modify your MAMake file to include the following:
  117.  
  118.     •    add the following to the list of OtherInterfaces
  119.         
  120.         "{SrcApp}UVUAssist.a" ∂
  121.         "{SrcApp}UVUAssist.p" ∂
  122.         "{SrcApp}UVUAssist.h"
  123.         
  124.     •    add the following to the list of OtherLinkFiles
  125.         
  126.         "{ObjApp}UVUAssist.a.o" ∂
  127.         "{ObjApp}UVUAssist.p.o" 
  128.     
  129.     •    add the additional dependency:
  130.  
  131.         "{ObjApp}UVUAssist.p.o"    ƒ ∂
  132.                     "{SrcApp}UVUAssist.p" ∂
  133.                     "{SrcApp}UVUAssist.inc1.p" ∂
  134.                     "{SrcApp}UVUAssist.inc2.p" ∂
  135.                     {MacAppIntf} ∂
  136.                     {BuildingBlocksIntf}
  137.                             
  138. 2)     Modify or subclass your descendant of TApplication to do the following:
  139.                             
  140.     •    In MyApplication.IApplication, you must execute this:
  141.             gVUAssist = new TVUAssist;
  142.             FailNIL(gVUAssist);
  143.             gVUAssist->IVUAssist(gridItemSupport); /* gridItemSupport must be a boolean 
  144.                                                     expression.  See "Altering the 
  145.                                                     behavior of VUAssist for an 
  146.                                                     explanation of gridItemSupport */
  147.  
  148.     •    In MyApplication.AboutToLoseControl you must execute this:
  149.             gVUAssist->SuspendMole();
  150.  
  151.     •    In MyApplication.RegainControl you must execute this:
  152.             gVUAssist->ResumeMole();
  153.  
  154.     •    In MyApplication.Close you must execute this BEFORE calling INHERITED Close:
  155.             this->InstallCohandler(gVUAssist,false);
  156.  
  157. 3)    Include the header file UVUAssist.h where appropriate.
  158.  
  159.         #ifndef __UVUASSIST__
  160.         #include "UVUAssist.h"
  161.         #endif
  162.         
  163.  
  164. 4)    If you are using C++, make sure to use the VUAssist.a file which is included 
  165.     in the folder "C++ Interface to VUAssist" in place of the file with the same 
  166.     name which is found in the folder "VUAssist Source Code".
  167.  
  168.  
  169. -----------------------------------------------------------------------------
  170. Modifying the Behavior of VUAssist
  171. -----------------------------------------------------------------------------
  172.  
  173. 1) VUAssist Idle Frequency
  174.  
  175. VUAssist has now been defined to be a descendant of TEvtHandler (or TEventHandler 
  176. in MacApp 3.0).  An application's responsiveness to V.U. queries can be controlled 
  177. by setting the idle frequency of VUAssist. Although nothing is done with this idle 
  178. time, it forces the application to awaken and call SystemTask with the application's 
  179. context switched in.  This is necessary for Agent VU, a driver, to get processing 
  180. time.  Agent VU, in turn, calls VUAssist.  So, in a roundabout way, the application's 
  181. responsiveness to V.U. can be controlled by setting the idle frequency of VUAssist.
  182.  
  183. By default, the idle frequency of VUAssist has been set to 1, the near maximum 
  184. frequency. You may want to alter this by executing the following statement:
  185.  
  186. gVUAssist.SetIdleFreq(newIdleFreq);
  187.  
  188. Note, however, that larger values of VUAssist's idle frequency will slow down the 
  189. application's responsiveness to V.U. unless there is another cohandler with a very 
  190. high idle frequency.
  191.  
  192.  
  193. 2) The gridItemSupport Argument
  194.  
  195. Note that the TVUAssist method IVUAssist now takes an argument, gridItemSupport.  
  196. This argument, if true, enables an optional feature of VUAssist where the cells 
  197. of gridviews are recognized as individual user interface items by V.U..  Virtual 
  198. User does not yet have a gridview or list descriptor.  So, for the short term, 
  199. the "gridItemSupport" feature treats each cell of a gridview as a "contentitem" 
  200. in the V.U. scripting language.
  201.  
  202. In applications with very large gridviews, it may not be desirable to treat each 
  203. cell in a gridview as a separate item in V.U..  This may hamper performance.  By 
  204. setting the value of the gridItemSupport argument to false, you will disable V.U.'s 
  205. griditem support feature and the cells of gridviews will not be seen as 
  206. "contentItems" by V.U..  The cells will be "invisible" to Virtual User.
  207.  
  208. **** WARNING!! *******************************************************************
  209. If the "gridItemSupport" feature is enabled, the following rules MUST be followed:
  210.  
  211. 1) Any descendants of TTextGridView in your application MUST override the method 
  212. TTextGridView.GetText.  This method is called by VUAssist to obtain the text 
  213. associated with a gridview cell. TTextGridView.GetText is a method which must be 
  214. overridden in MacApp. 
  215.  
  216. 2) For reasons analogous to those above, any descendants of TTextListView in your 
  217. application MUST override the method TTextListView.GetItemText.  
  218. TTextListView.GetText need not be overridden.
  219. ***********************************************************************************
  220.  
  221.  
  222.  
  223.